<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Build">
   <title>DRAFT for RFC 0004 - Marker Position Updates</title>
</head>
<body bgcolor="#FFFFFF" >
<div align="right">
  <table border=0 cellspacing=0 cellpadding=2 width="100%">
    <tr> 
		<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">
			Request For Comment
		</font></font></b></td>
    </tr>
  </table>
</div>
<div align="left"> 
  <h1><img src="../images/idea.gif" width="120" height="86"></h1>
</div>
<h1 align="CENTER">DRAFT of RFC 0004</h1>
<h1 align="CENTER">Marker Position Updates</h1>
<blockquote> 
  <p><b>Summary</b> <br>
    When files in the workspace are modified, attributes of markers in those
    files, such as character and line positions, may become invalid.  A general,
    centralized mechanism is needed for updating marker attributes after
    file modifications.
  <p><b> By John Arthorne, OTI.</b> <br>
    <font size="-1">Created: November 29, 2001</font><br>
    <font size="-1">Last Modified: December 4, 2001</font><br>
  </blockquote>
<hr>
<h2>Motivation</h2>
<p>
There are many different components that perform textual manipulation of files.
Some examples in the Eclipse Platform SDK include: editors, the JDOM API for 
manipulating java elements, the java refactoring API, and the compare framework.  
When file contents are changed, it may cause some of the attributes of markers on 
those files to become invalid.  For example, if lines are added to a text file in an editor, 
the <tt>CHAR_START</tt>, <tt>CHAR_END</tt>, and <tt>LINE_NUMBER</tt> attributes 
of text markers may need to be updated.
</p>
<p>
Currently, each component that performs text manipulations is responsible for updating
any marker attributes that may be affected by the change.  This leads to a duplication
of the update algorithms in several places.  Furthermore, different marker types may
need to be updated in different ways.  For example, if an extra comment line is added
to a java source file, it may be appropriate to move any breakpoints on that line
down to the next line with a valid java statement, but it might make sense to leave
a bookmark at its original location.  In the current story, if marker-specific updates
are needed, each component that manipulates files would need to know how to update
each marker type.  This knowledge is not always possible; for example the text editor
does not know about java breakpoints.
</p>
<p>
The purpose of this proposal is to provide a central point where components that
manipulate files can trigger the file's markers to be updated.  This central point
should know how to update each marker type that has a unique update strategy.
</p>
<h2>Proposed Solution</h2>
<h3>Update API</h3>
<p>
The initial proposal is to add a method to IFile.  This is based on the description provided by Jeem:
<pre>
/**
 * Updates the text markers in this file, based on the provided edit information.
 * @param replaceStart The character position at the start of the replaced range. This value
 *		is zero-relative and inclusive.
 * @param replaceEnd The character position at the end of the replaced range.  This value
 *		is zero-relative and exclusive.
 * @param replaceSize The size of the new block that replaced the range described by
 *		replaceStart and replaceEnd.
 * @throws CoreException If this method fails.  Reasons include:
 * &lt;ul&gt;
 * &lt;li&gt;The given range is invalid.&lt;/li&gt;
 * &lt;/ul&gt;
 */
public void updateMarkers(int replaceStart, int replaceEnd, int replaceSize) throws CoreException;
</pre>
The idea is that this API can describe any single edit to a file.  Examples (again from Jeem):
<ol>
<li>updateMarkers(0, 100, 10) - replace first 100 characters of file with ten characters.</li>
<li>updateMarkers(200, 300, 0) - delete the character range from 200 to 300.</li>
<li>updateMarkers(400,400, 1) - Add a character at position 400.</li>
</ol>
<h3>Extensibility API</h3>
<p>
Some marker types may require a special update algorithm.  The idea is to provide
a way for marker types to define how marker updates occur through the markers
extension point.  The proposal is to add an extra optional element to a marker definition,
to plug in a marker update algorithm.  Here is an example marker definition:
<pre>
&lt;extension 
	id="mycustommarker" 
	point="org.eclipse.core.resources.markers" 
	name="The Foo Marker"&gt;
  &lt;super type="org.eclipse.core.resources.textmarker" /&gt;
  &lt;persistent value="true" /&gt;
  &lt;update class="org.xyz.foo.FooMarkerUpdate"&gt;
  &lt;/extension&gt;
</pre>
The update class would implement a new interface, 
<A HREF="IMarkerUpdate.html">IMarkerUpdate</A>.  This interface
has a method similar to the updateMarkers method described above.  Markers
with no update class specified inherit a marker update from one of their marker supertypes.
Supertypes would be searched breadth-first, in the order the supertypes appear in the
marker declaration (or perhaps in an indeterminate order).  Core will provide IMarkerUpdates
for the standard marker types that it defines (marker, text marker, problem, task, bookmark).
</p>
<p>
<b>Open Question:</b> Line number update.  How the LINE_NUMBER attribute will be
updated is an open question.  One possibility is that there would be two separate
methods, one for character updates, and one for line updates.  It is not known if or
how the various marker types make use of the LINE_NUMBER attribute.  Perhaps it
is redundant information and can be recomputed on demand when needed.  A character
update algorithm could theoretically infer the line number changes, but this would require
knowledge of line terminators, etc.  This would also be significantly slower if it required
an independent scan of the file to recompute line numbers during update.
</p>
<h2>RFC Status</h2>
<p>This RFC has been shelved for consideration after the 2.0 release.  The interested parties 
have not yet achieved consensus on the form a marker update mechanism should take.
<br>Comments should be directed to the core mailing list: 
<a href="http://dev.eclipse.org/mailman/listinfo/platform-core-dev">platform-core-dev@eclipse.org</a> 
(<a href="mailto:platform-core-dev@eclipse.org">post</a>, 
<a href="http://dev.eclipse.org/mhonarc/lists/platform-core-dev/maillist.html">archives</a>).
</p>
</body>
</html>